Skip to content

Edit credentials summary similar to spec #39569

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+6 −2
Open

Edit credentials summary similar to spec #39569

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6062079
Edit credentials summary similar to spec
DanKaplanSES May 19, 2025
c606d33
Add additional details to credentials section
DanKaplanSES May 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions files/en-us/web/api/fetch_api/using_fetch/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -205,9 +205,13 @@ See the reference documentation for {{domxref("RequestInit", "", "mode")}} for m

### Including credentials

Credentials are cookies, {{glossary("TLS")}} client certificates, or authentication headers containing a username and password.
In the context of an HTTP request, a credential is an extra piece of data sent along with the request, that the server may use to authenticate the user. All the following items are considered to be credentials:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wbamberg This is a huge improvement. I also think the definitive guide should be in this file because it's easy to digest and has a high likelihood of being applicable to your first usage.

I had some edits to suggest, but I'm mostly interested in your thoughts about this one:

Suggested change
In the context of an HTTP request, a credential is an extra piece of data sent along with the request, that the server may use to authenticate the user. All the following items are considered to be credentials:
In the context of a `fetch` request, a credential is an extra piece of data sent along with the request that the server may use to authenticate the user. All the following items are considered to be credentials:

I'm assuming that this definition is specific to the fetch API, not all of HTTP. e.g., a curl command with a credentials header wouldn't behave the way this section describes, would it?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure, I'm happy with this, although "fetch" here should not get code formatting because it isn't an identifier in this context.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@wbamberg I'm not sure what you mean by "an identifier in the context." Perhaps you could word it a different way?

FWIW, the reason I used code formatting was to emphasize it applies to the fetch API, not HTTP in general, and I think the word "fetch" is used colloquially to mean, "A client initiates a call to a server." I didn't want a reader to mistakenly interpret it that way.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean, there's no code entity which we'd refer to as fetch. There's a fetch() method, and we would use code formatting it we wanted to say something like "When you call fetch()...". When we talk about "the fetch API" we're talking about an abstraction. In the rest of this guide, and in the overview page, we actually capitalize it, like "the Fetch API".

If you wanted, you could say "In the context of the Fetch API, ...".


To control whether or not the browser sends credentials, as well as whether the browser respects any **`Set-Cookie`** response headers, set the `credentials` option, which can take one of the following three values:
- HTTP cookies
- {{glossary("TLS")}} client certificates
- The {{httpheader("Authorization")}} and {{httpheader("Proxy-Authorization")}} headers.

By default, credentials are only included in same-origin requests. To customize this behavior, as well as to control whether the browser respects any **`Set-Cookie`** response headers, set the [`credentials`](/en-US/docs/Web/API/RequestInit#credentials) option, which can take one of the following three values:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the Set-Cookie response is handled differently for each of these bullet points. If I'm understanding that correctly, it may make sense to add the specifics in each one.

Copy link
Collaborator

@wbamberg wbamberg May 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose "include credentials in the response" in bullet 1 and "send and include credentials" in bullet 2 are clumsy ways of saying "include the Set-Cookie response header" (since it doesn't make sense to include, say, TLS client certificate in a response). Similarly in the later bullets about "the response, including credentials, will be delivered to the caller".

It would be better to be clear that this is (AFAICT) specifically about Set-Cookie.

It's a very complicated corner of the fetch API, and one that I tried to improve when I rewrote this doc, but there's definitely still room for improvement!


- `omit`: never send credentials in the request or include credentials in the response.
- `same-origin` (the default): only send and include credentials for same-origin requests.
Expand Down